How to Use Social Proof API

To locate and obtain an API Key of a client’s eCommerce site:

1. Log in to Omnichannel Personalization.
2. On the Omnichannel Personalization Dashboard page, in the left pane, click the customer site name from the dropdown list and then select the required client name.
3. Click available next to the Customer Site Name dropdown list. The Site-info window is displayed.

   

4. From the Site-info window, copy the API Key and save it to your drive.

GET method is used to get the responses.

GET/rrserver/api/productEventsMetrics/spEvents?apiKey={apiKey}&productId={productId}&eventType=eventType}&timeWindow={timeWindow}&s={sessionId}&u={userId}&rcs={remoteCookieStoreValue}

Request Call Parameters

The following parameters are used for RR-Server SP-API.

• SiteDenotedUserIdCount: It is the unique user count based on mvt-seed-type id. This is part of Site Configurations RR.

• eventCount: It is the purchase/add-to-cart event count for the eventType and timeWindow.

• timeWindow: It is the time interval of user's last visit to the nearest interval available.

• isPersonalizedForLastVisit: It is a flag for personalized messaging which is set to true or false according to the match of user's last visit and the nearest timeWindow.

Without eventType & timeWindow

Note: This call is currently used for item-page.

https://recs.richrelevance.com/rrserver/api/productEventsMetrics/spEvents?apiKey=b94cb8fe7be1ff1c&productId=V_87654321

For Purchase Event

https://recs.richrelevance.com/rrserver/api/productEventsMetrics/spEvents?apiKey=b94cb8fe7be1ff1c&productId=V_87654321&eventType=purchases

For One Hour Time Window

https://recs.richrelevance.com/rrserver/api/productEventsMetrics/spEvents?apiKey=b94cb8fe7be1ff1c&productId=V_87654321&timeWindow=60

For Purchase Event with One Hour Time Window

https://recs.richrelevance.com/rrserver/api/productEventsMetrics/spEvents?apiKey=b94cb8fe7be1ff1c&productId=V_87654321&eventType=purchases&timeWindow=60

For Multiple Product IDs

For product-id: V_01234567 & V_87654321 for purchase events with 12 hours’ time window

https://recs.richrelevance.com/rrserver/api/productEventsMetrics/spEvents?apiKey=b94cb8fe7be1ff1c&productId=V_01234567|V_87654321&eventType=purchases&timeWindow=720

Social Proof now provides personalized messages to a shopper about other shoppers’ interactions on the app which include product page viewed, product added to cart (ATC), and product purchased by the other shoppers since the last visit of the shopper.

For example, a personalized message to a shopper showing interaction of other shoppers with a product looks like this: “25 people purchased this item since your last visit”. Another example is: “45 people visited this page since your last visit”.

If a shopper visits a product page second time within certain hours span, such personalized messages are displayed for them on their second visit. These messages provide engagement with the product and generate high confidence among the shoppers.

Metrics Views, ATC, Purchases, and Inventory are captured for every 2-hour interval and mapped to the user's last visit to the nearest interval available. The metrics are available for products for every 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, and 24 hours as a dynamic experience.

For example, if a shopper visits a product’s page 7.5 hours after their first visit, then the nearest interval that matches the shopper’s second visit falls between 6-hour and 8-hour intervals. Thus, the views, ATC, purchases, and inventory of the 8-hour interval are considered and shown as part of the personalized messages to the shopper.

Clients can also change dynamic experience for ‘today’ metrics from 24 hours to 12 hours.

API perspective

For each product, the following metrics are captured for each Metric/Interval.

• Views (event type)

• 1440 minutes or 24-hour interval (time window)

When user's last visit (7.5 hours ago) matches the nearest time window (8 hour window), then the flag IsPersonalizedForLastVisit is set to true. The views/ATC/purchases/inventory with the flag as true are the metrics for personalized messaging for the item page for the user.

There are two ways to show the count of product views, add to cart, purchases, and inventory:

• Number of people interacted with the product

• Number of events associated with the product

By default, user count is used as a metric for social proof messaging. However, it can be changed from user count to event count (currently through JavaScript and through UI in the future).

Showing number of people interacted with the product

The number of people interacting with the product is captured in real time:

• Views Right Now: The number of people who viewed the product for the last 15 minutes are captured (It refreshes every 45 seconds).

• Add To Cart (ATC)/Purchases: The number of people who added the product to the cart and purchased are captured for every 1 hour/60 minutes (It refreshes every 1 min).

• Views/ATC/Purchases Today: The number of people who viewed/added to the cart/purchased is captured every for 12 hours/720 minutes (Today).

From the API, SiteDenotedUserIdCount provides the user count (number of people interacting).

Showing number of events (Views/ATC/Purchases) associated with the product

From the API, eventCount provides the number of views, products added to the cart, and the number of purchases.

Difference between eventCount and SiteDenotedUserIdCount

When 1 user makes 10 purchases, it results in the following:

• User Count (siteDenotedUserIdCount) = 1

  When the user count metric is used, then the number of users is shown.

  For example, X people are purchasing this product right now.

• Event count (eventCount) = 10

  When the event count metric is used, the number of purchases is shown.

  For example, X purchases right now.

The 7 days interval enables the API response to include the metrics - Views/ATC/Purchases/Inventory for the intervals of 2 days, 3 days, 4 days, 5 days, 6 days, and 7 days along with the existing intervals - Right Now/Last 1 hour/Today.

Note: The 7 days interval feature is not enabled by default for all the customers, hence contact the Algonomy Support Team to enable this feature.

API Response Examples

• For 2 days interval (timewindow = 2880 Min)

  

• For 6 days interval (timewindow = 8640 min)

  

• For 7 days interval (timewindow = 10080 min)

  

The event count and user count are calculated as the sum of today’s count (from 0 hour to current time) + Last days count

For 7 days Interval = Today’s count + Last 6 days count

Social Proof API response includes Inventory remaining as a new parameter. It is calculated from Inventory Quantity (come from catalog feed) and the purchases that have happened from the last update of the inventory quantity. It is added as inventory messaging to persuade users to purchase. Inventory depends on providing inventory level for products in the catalog.

Customers should send both Inventory Quantity and Inventory Updated Time through Catalog feed and set the site configuration parameters with the names of the fields that they send through the feed.

Social Proof Inventory Messaging is to display an estimate of total available inventory quantity for a given siteId and productId combination at any point of time. At RR server, in the existing implementation, when it receives sp-events-metrics response from sp-api, a new field inventory quantity will be added and sent as a final response.

The product catalog needs to include the following to identify the attributes used for inventory messaging:

• Inventory level : By default, the key name defined in the site configuration for inventory level is 'inventory_quantity'.

• Timestamp for inventory level: By default, the key name defined in the site configuration for inventory timestamp is 'inventory_quantity_update_time'.

Site Configuration for Inventory Messaging

Perform the following steps to set up the site configuration of Inventory Messaging:

1. On the Omnichannel PersonalizationDashboard page, go to Admin > Site Configurations RR.

2. In the search box, type 'inventory' to view the inventory related configurations.

3. In the other site configurations area, specify the following keys:

   • inventory quantity key: Click and specify the key as inventory_quantity.

   • inventory quantity update time key: Click and specify the key as inventory_quantity_update_time.

   Note: The customers either can provide their own key name or keep the default key name displayed in the placeholder.

   

4. Based on the values shared, the inventory quantity is estimated considering the purchases that happened for a particular time period. If no purchases are present, then set the values as displayed.

5. Restart the core/rrserver module.

Use Cases

Following are the use cases for Inventory Messaging:

• Use Case 1: inventoryQuantityComputed time Window = 60min(1hr)

  Inventory Quantity = 500

  Event count = 150

  feed time = 21:45 on 12 th oct

  Cassandra time = 22:55 on 12 th oct (Cassandra time should be less than 1 hr(feed time - cassandra))

  API Hit = 22:15 on 12 th oct - showing 500 quantity diff time (30)

  API Hit = 22:27 : showing 400 Diff time (42 min)

  API Hit = 22:35 : showing 400 Diff time (52 min)

  API Hit = 22:45 : showing 400 Diff time (60 min) - 1h

  API Hit = 23:00 : showing Diff time 400 (75 min)

  API Hit = 23:15 : showing 400 Diff time (90 min)

  In the sp api result inventory count is showing as 400

• Use Case 2: inventoryQuantityComputed time Window = 120min(2hr)

  Inventory Quantity = 500

  Event count = 150

  feed time = 21:45 on 12 th oct

  Cassandra time = 23:30 on 12 th oct (Cassandra time should be less than 2 hrs(feed time - cassandra))

  API Hit = 23:30 : showing 350 Diff time (105 min)

  API Hit = 23:45 : showing 350 Diff time (120 min) - 2 hrs

  API Hit = 00:00 : showing 350 Diff time (135 min)

  API Hit = 00:15 : showing 350 Diff time (150 min)

  API Hit = 00:30 : showing 350 Diff time (165 min)

  API Hit = 00:45 : showing 300Diff time (165 min)

  In the sp api result inventory count is showing as 350

• Use Case 3: inventoryQuantityComputed time Window = 240min(4hr)

  Inventory Quantity = 500

  Event count = 200

  feed time = 21:45 on 12 th oct

  Cassandra time = 1:30 on 13 th oct (Cassandra time should be less than 4 hrs (feed time - cassandra))

  API Hit = 1:00 : showing Diff time (195 min)

  API Hit = 1:15 : showing Diff time (210 min)

  API Hit = 1:30 : showing 300 Diff time (225 min)

  API HIt time = 1:45 showing 300 Diff time (240 min) - 4hrs

  In the sp api result inventory count is showing as 300**

• Use Case 4: inventoryQuantityComputed time Window = 360min(6hr)

  Inventory Quantity = 500

  Event count = 250

  feed time = 21:45 on 12 th oct

  Cassandra time = 3:30 on 13 th oct

  API HIT = 2:48 on 13 th oct showing 250 Diff time (303 m)

  API HIT = 3:45 on 13 th oct showing 250 Diff time (360 min) - 6hrs

  In the sp api result inventory count is showing as 250**

• Use Case 5: When time difference is between 0 to lowestInterval/2

  Total quantity is displayed in the feed time.

• Use Case 6: When time difference is greater than the maximum window interval available.

  The Inventory Quantity is displayed as -1.

This section provides information on how to incorporate dynamic count parameters into social proof messaging. The dynamic count parameters include user count and event count which allow you to display the number of users or events associated with a product in your social proof message. Additionally, this section also explains how to switch between using user count and event count as a metric in the social proof message.

Dynamic Count Parameters

The dynamic count parameters enable you to include the count of users or events in your social proof message. By default, the text includes the user count parameter as "@usercount people viewed today". However, you can place the "@usercount" parameter anywhere within the message text. This allows you to customize the message according to your requirements. For example, if you want to display a message like "Popular! 10 people viewed today," you can modify the text as "Popular! @usercount people viewed today".

Social Proof Metrics

Social proof provides two types of metrics for product interactions which are user count and event count. These metrics help to demonstrate the popularity and engagement associated with a product. The metrics can be used to track product views, adds to cart, purchases, and inventory.

• User Count: This metric represents the number of unique individuals who have interacted with the product.

• Event Count: This metric indicates the total number of events associated with the product including all interactions.

Switching Metrics

By default, the user count is used as the metric for social proof messaging. However, you have the flexibility to switch between using user count and event count based on your preference. When you change the metric, the corresponding count will be used for both the message text and the threshold.

To update the message text to display the event count, you can use the following formats:

• "@eventcount views today"

• "Popular! @eventcount views today"

By incorporating the "@eventcount" parameter in the message text, you can showcase the event count in your social proof message.

Threshold Selection

When determining the threshold for social proof messaging, the same metric used in the message text will also be utilized. For instance, if you choose to display the user count in the message text, the threshold will be based on the number of users. Similarly, if the event count is included in the message text, the threshold will be based on the number of events.

Note: Ensure that the chosen metric aligns with your intended message and accurately reflects the desired social proof for your product.

The following page types are mapped to the appropriate templates as listed below. Once the page type is selected, social proof message should show appropriately based on the template that is mapped.

Implementing detailed tracking of social proof messages through the Experience API enables a more thorough analysis of message effectiveness. The Experience API to provide detailed insights into the display of social proof messages to shoppers. By specifying the exact message displayed, the API facilitates a comprehensive analysis of message effectiveness, enabling data-driven optimization strategies. The Experience API offers enhanced granularity by conveying specific information about the displayed message. This includes the following scenarios:

• Single Message Display: The API will now pass the actual social proof message displayed when the threshold is met.

  For example, SP Message shown - Actual Social Proof Message.

• Multiple Message Display: When multiple messages meet the threshold, the API will append a note indicating eligibility for multiple messages, along with the actual message displayed.

• No Message: If the threshold criteria are not met and no social proof message is displayed, the API will indicate "No Message - threshold not satisfied".

• Error Handling: Clear error messages will be provided in case of any issues encountered.

The Social Proof API enables to display multiple messages across Add-to-Cart, Category, and Item pages, overcoming the limitation of showing only one message for multiple products. This enhancement allows for the presentation of several messages that meet the threshold as part of social proof messaging. Additionally, the API supports multiple products for various intervals and event types, aligning with the functionality available for Item pages. It can handle up to 100 products on Category and Search pages and less than 15-20 products on Cart pages, catering to the diverse needs of digital storefronts.

Social proof is enhanced to engage users and boost click-through rates through the inclusion of social proof messaging within product recommendations. This feature enables you to show more than one social proof message on the same page type, to show social proof messages using the 'List page' template on product recommendations and ensuring that users see messages relevant to their current journey. The importance of these messages is determined by placement type and template type, allowing you to deliver a customized experience.

Configuring social proof messaging is simple, with templates aligned with the existing list page configurations. You can specify where messages are applied by entering placement names, ensuring precise control over message placement. This enhancement empowers you to provide users with context-aware content, improving their shopping experience and increasing engagement.

Social Proof messaging can be displayed on the recommendations on any of the pages. Selecting the location (anchoring element type & attribute) is the only element that drives the social proof messaging.

• Showing Social Proof Messaging on Item Page Recommendations

  The client needs to select placement context along with the page type so that the social proof message can be shown on the recommendation placements.

  Note: When the placement context is selected along with page type, the template will be set to the list page. Therefore, the user will only be able to select one message type in this case.

• Showing Social Proof Messaging on List Page Recommendations (or any other pages)

  The location selector is the only element that drives the social proof messaging. Therefore, it does not require any setup other than selecting an appropriate unique location to the placement of social proof message that you want to show.

• If you want only one placement to show the social proof message (out of many placements on the item page), ensure the location of the social proof message to be displayed is unique to that placement. The placement selection (in Item page template) is only to ensure the template is mapped to the list page.

Social Proof has enhanced its message display capability by introducing language parameter support. This allows merchants to specify the desired language for social proof messages, ensuring users receive messages in their preferred language. This includes the following benefits:

• Multi-Language Configuration: Merchandisers can configure social proof messages for multiple languages using a unified template, specifying messages in the appropriate locale for each language.

• Localized Text Entry: Users can input text for each specified language directly within the user interface, ensuring precise localization. This feature simplifies the setup and management of localized messages.

• Dynamic Messaging Display: Social proof messages dynamically adapt to display the appropriate text based on language parameters provided in the R3_COMMON configuration. This includes support for language (lang) parameters, enabling the direct display of corresponding text when the language parameter is passed.

Language Parameter

The Social Proof Output Response API now accepts the language parameter (lang), allows to display messages in the specified language. This ensures seamless integration with applications, enabling users to receive messages in their preferred language through server-side interactions.

The 'lang' parameter enables language-specific customization within the Social Proof Output Response API. Specifying this parameter ensures that messages are displayed in the user's preferred language, enhancing the overall user experience across different locales.

{
    "name": "purchases_in_the_last_hour_threshold",
    "value": "1",
    "allowedValues": null,
    "description": "Template.socialProofingItemPage.variable.purchases_in_the_last_hour_threshold",
    "placeholder": null,
    "allowedValuesVariable": null,
    "dependentListId": null,
    "dependentByValue": null,
    "questionType": null,
    "optionsAPI": null,
    "type": "NUMBER",
    "lang-en": "@usercount viewed this today",
    "lang-de": "@usercount hat sich das heute angesehen"
}

The following points outline the key features and functionalities of the 'lang' parameter within the Social Proof Output Response API:

• lang-en: Message template in English.

• lang-de: Message template in German.